home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-16 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  47KB  |  846 lines
  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: Major Mode Conventions,  Next: Example Major Modes,  Prev: Major Modes,  Up: Major Modes
  20. Major Mode Conventions
  21. ----------------------
  22.    The code for existing major modes follows various coding conventions,
  23. including conventions for local keymap and syntax table initialization,
  24. global names, and hooks.  Please keep these conventions in mind when you
  25. create a new major mode:
  26.    * Define a command whose name ends in `-mode', with no arguments,
  27.      that switches to the new mode in the current buffer.  This command
  28.      should set up the keymap, syntax table, and local variables in an
  29.      existing buffer without changing the buffer's text.
  30.    * Write a documentation string for this command which describes the
  31.      special commands available in this mode.  `C-h m'
  32.      (`describe-mode') will print this.
  33.      The documentation string may include the special documentation
  34.      substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
  35.      enable the documentation to adapt automatically to the user's own
  36.      key bindings.  *Note Keys in Documentation::.  The `describe-mode'
  37.      function replaces these special documentation substrings with
  38.      their current meanings.  *Note Accessing Documentation::.
  39.    * The major mode command should set the variable `major-mode' to the
  40.      major mode command symbol.  This is how `describe-mode' discovers
  41.      which documentation to print.
  42.    * The major mode command should set the variable `mode-name' to the
  43.      "pretty" name of the mode, as a string.  This appears in the mode
  44.      line.
  45.    * Since all global names are in the same name space, all the global
  46.      variables, constants, and functions that are part of the mode
  47.      should have names that start with the major mode name (or with an
  48.      abbreviation of it if the name is long).  *Note Style Tips::.
  49.    * The major mode should usually have its own keymap, which is used
  50.      as the local keymap in all buffers in that mode.  The major mode
  51.      function should call `use-local-map' to install this local map.
  52.      *Note Active Keymaps::, for more information.
  53.      This keymap should be kept in a global variable named
  54.      `MODENAME-mode-map'.  Normally the library that defines the mode
  55.      sets this variable.  Use `defvar' to set the variable, so that it
  56.      is not reinitialized if it already has a value.  (Such
  57.      reinitialization could discard customizations made by the user.)
  58.    * The mode may have its own syntax table or may share one with other
  59.      related modes.  If it has its own syntax table, it should store
  60.      this in a variable named `MODENAME-mode-syntax-table'.  The reasons
  61.      for this are the same as for using a keymap variable.  *Note
  62.      Syntax Tables::.
  63.    * The mode may have its own abbrev table or may share one with other
  64.      related modes.  If it has its own abbrev table, it should store
  65.      this in a variable named `MODENAME-mode-abbrev-table'.  *Note
  66.      Abbrev Tables::.
  67.    * To give a variable a buffer-local binding, use
  68.      `make-local-variable' in the major mode command, not
  69.      `make-variable-buffer-local'.  The latter function would make the
  70.      variable local to every buffer in which it is subsequently set,
  71.      which would affect buffers that do not use this mode.  It is
  72.      undesirable for a mode to have such global effects.  *Note
  73.      Buffer-Local Variables::.
  74.    * If hooks are appropriate for the mode, the major mode command
  75.      should run the hooks after completing all other initialization so
  76.      the user may further customize any of the settings.  *Note Hooks::.
  77.    * If this mode is appropriate only for specially-prepared text, then
  78.      the major mode command symbol should have a property named
  79.      `mode-class' with value `special', put on as follows:
  80.           (put 'funny-mode 'mode-class 'special)
  81.      This tells Emacs that new buffers created while the current buffer
  82.      has Funny mode should not inherit Funny mode.  Modes such as
  83.      Dired, Rmail, and Buffer List use this feature.
  84.    * If it is desirable that Emacs use the new mode by default after
  85.      visiting files with certain recognizable names, add an element to
  86.      `auto-mode-alist' to select the mode for those file names.  If you
  87.      define the mode command to autoload, you should add this element
  88.      in the same file that calls `autoload'.  Otherwise, it is
  89.      sufficient to add the element in the file that contains the mode
  90.      definition.  *Note Auto Major Mode::.
  91.    * In the documentation, you should provide a sample `autoload' form
  92.      and an example of how to add to `auto-mode-alist', that users can
  93.      include in their `.emacs' files.
  94.    * The top level forms in the file defining the mode should be
  95.      written so that they may be evaluated more than once without
  96.      adverse consequences.  Even if you never load the file more than
  97.      once, someone else will.
  98. File: elisp,  Node: Example Major Modes,  Next: Auto Major Mode,  Prev: Major Mode Conventions,  Up: Major Modes
  99. Major Mode Examples
  100. -------------------
  101.    Text mode is perhaps the simplest mode besides Fundamental mode.
  102. Here are excerpts from  `text-mode.el' that illustrate many of the
  103. conventions listed above:
  104.      ;; Create mode-specific tables.
  105.      (defvar text-mode-syntax-table nil
  106.        "Syntax table used while in text mode.")
  107.      (if text-mode-syntax-table
  108.          ()              ; Do not change the table if it is already set up.
  109.        (setq text-mode-syntax-table (make-syntax-table))
  110.        (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
  111.        (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
  112.        (modify-syntax-entry ?' "w   " text-mode-syntax-table))
  113.      (defvar text-mode-abbrev-table nil
  114.        "Abbrev table used while in text mode.")
  115.      (define-abbrev-table 'text-mode-abbrev-table ())
  116.      (defvar text-mode-map nil)   ; Create a mode-specific keymap.
  117.      
  118.      (if text-mode-map
  119.          ()              ; Do not change the keymap if it is already set up.
  120.        (setq text-mode-map (make-sparse-keymap))
  121.        (define-key text-mode-map "\t" 'tab-to-tab-stop)
  122.        (define-key text-mode-map "\es" 'center-line)
  123.        (define-key text-mode-map "\eS" 'center-paragraph))
  124.    Here is the complete major mode function definition for Text mode:
  125.      (defun text-mode ()
  126.        "Major mode for editing text intended for humans to read.
  127.       Special commands: \\{text-mode-map}
  128.      Turning on text-mode runs the hook `text-mode-hook'."
  129.        (interactive)
  130.        (kill-all-local-variables)
  131.      (use-local-map text-mode-map)     ; This provides the local keymap.
  132.        (setq mode-name "Text")           ; This name goes into the mode line.
  133.        (setq major-mode 'text-mode)      ; This is how `describe-mode'
  134.                                          ;   finds the doc string to print.
  135.        (setq local-abbrev-table text-mode-abbrev-table)
  136.        (set-syntax-table text-mode-syntax-table)
  137.        (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
  138.                                          ;   customize the mode with a hook.
  139.    The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
  140. Interaction mode) have more features than Text mode and the code is
  141. correspondingly more complicated.  Here are excerpts from
  142. `lisp-mode.el' that illustrate how these modes are written.
  143.      ;; Create mode-specific table variables.
  144.      (defvar lisp-mode-syntax-table nil "")
  145.      (defvar emacs-lisp-mode-syntax-table nil "")
  146.      (defvar lisp-mode-abbrev-table nil "")
  147.      (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
  148.                                             ;   if it is already set.
  149.          (let ((i 0))
  150.            (setq emacs-lisp-mode-syntax-table (make-syntax-table))
  151.      ;; Set syntax of chars up to 0 to class of chars that are
  152.            ;;   part of symbol names but not words.
  153.            ;;   (The number 0 is `48' in the ASCII character set.)
  154.            (while (< i ?0)
  155.              (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
  156.              (setq i (1+ i)))
  157.            ...
  158.      ;; Set the syntax for other characters.
  159.            (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
  160.            (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
  161.            ...
  162.      (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
  163.            (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
  164.            ...))
  165.      ;; Create an abbrev table for lisp-mode.
  166.      (define-abbrev-table 'lisp-mode-abbrev-table ())
  167.    Much code is shared among the three Lisp modes.  The following
  168. function sets various variables; it is called by each of the major Lisp
  169. mode functions:
  170.      (defun lisp-mode-variables (lisp-syntax)
  171.        ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
  172.        ;;   and `t' in the other two Lisp modes.
  173.        (cond (lisp-syntax
  174.               (if (not lisp-mode-syntax-table)
  175.                   ;; The Emacs Lisp mode syntax table always exists, but
  176.                   ;;   the Lisp Mode syntax table is created the first time a
  177.                   ;;   mode that needs it is called.  This is to save space.
  178.      (progn (setq lisp-mode-syntax-table
  179.                             (copy-syntax-table emacs-lisp-mode-syntax-table))
  180.                          ;; Change some entries for Lisp mode.
  181.                          (modify-syntax-entry ?\| "\"   "
  182.                                               lisp-mode-syntax-table)
  183.                          (modify-syntax-entry ?\[ "_   "
  184.                                               lisp-mode-syntax-table)
  185.                          (modify-syntax-entry ?\] "_   "
  186.                                               lisp-mode-syntax-table)))
  187.      (set-syntax-table lisp-mode-syntax-table)))
  188.        (setq local-abbrev-table lisp-mode-abbrev-table)
  189.        ...)
  190.    Functions such as `forward-paragraph' use the value of the
  191. `paragraph-start' variable.  Since Lisp code is different from ordinary
  192. text, the `paragraph-start' variable needs to be set specially to
  193. handle Lisp.  Also, comments are indented in a special fashion in Lisp
  194. and the Lisp modes need their own mode-specific
  195. `comment-indent-function'.  The code to set these variables is the rest
  196. of `lisp-mode-variables'.
  197.      (make-local-variable 'paragraph-start)
  198.        (setq paragraph-start (concat "^$\\|" page-delimiter))
  199.        ...
  200.      (make-local-variable 'comment-indent-function)
  201.        (setq comment-indent-function 'lisp-comment-indent))
  202.    Each of the different Lisp modes has a slightly different keymap.
  203. For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
  204. Lisp modes do not.  However, all Lisp modes have some commands in
  205. common.  The following function adds these common commands to a given
  206. keymap.
  207.      (defun lisp-mode-commands (map)
  208.        (define-key map "\e\C-q" 'indent-sexp)
  209.        (define-key map "\177" 'backward-delete-char-untabify)
  210.        (define-key map "\t" 'lisp-indent-line))
  211.    Here is an example of using `lisp-mode-commands' to initialize a
  212. keymap, as part of the code for Emacs Lisp mode.  First we declare a
  213. variable with `defvar' to hold the mode-specific keymap.  When this
  214. `defvar' executes, it sets the variable to `nil' if it was void.  Then
  215. we set up the keymap if the variable is `nil'.
  216.    This code avoids changing the keymap or the variable if it is already
  217. set up.  This lets the user customize the keymap if he or she so wishes.
  218.      (defvar emacs-lisp-mode-map () "")
  219.      
  220.      (if emacs-lisp-mode-map
  221.          ()
  222.        (setq emacs-lisp-mode-map (make-sparse-keymap))
  223.        (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
  224.        (lisp-mode-commands emacs-lisp-mode-map))
  225.    Finally, here is the complete major mode function definition for
  226. Emacs Lisp mode.
  227.      (defun emacs-lisp-mode ()
  228.        "Major mode for editing Lisp code to run in Emacs.
  229.      Commands:
  230.      Delete converts tabs to spaces as it moves back.
  231.      Blank lines separate paragraphs.  Semicolons start comments.
  232.      \\{emacs-lisp-mode-map}
  233.      Entry to this mode runs the hook `emacs-lisp-mode-hook'."
  234.        (interactive)
  235.        (kill-all-local-variables)
  236.        (use-local-map emacs-lisp-mode-map)    ; This provides the local keymap.
  237.        (set-syntax-table emacs-lisp-mode-syntax-table)
  238.      (setq major-mode 'emacs-lisp-mode)     ; This is how `describe-mode'
  239.                                               ;   finds out what to describe.
  240.        (setq mode-name "Emacs-Lisp")          ; This goes into the mode line.
  241.        (lisp-mode-variables nil)              ; This define various variables.
  242.        (run-hooks 'emacs-lisp-mode-hook))     ; This permits the user to use a
  243.                                               ;   hook to customize the mode.
  244. File: elisp,  Node: Auto Major Mode,  Next: Mode Help,  Prev: Example Major Modes,  Up: Major Modes
  245. How Emacs Chooses a Major Mode
  246. ------------------------------
  247.    Based on information in the file name or in the file itself, Emacs
  248. automatically selects a major mode for the new buffer when a file is
  249. visited.
  250.  - Command: fundamental-mode
  251.      Fundamental mode is a major mode that is not specialized for
  252.      anything in particular.  Other major modes are defined in effect
  253.      by comparison with this one--their definitions say what to change,
  254.      starting from Fundamental mode.  The `fundamental-mode' function
  255.      does *not* run any hooks, so it is not readily customizable.
  256.  - Command: normal-mode &optional FIND-FILE
  257.      This function establishes the proper major mode and local variable
  258.      bindings for the current buffer.  First it calls `set-auto-mode',
  259.      then it runs `hack-local-variables' to parse, and bind or evaluate
  260.      as appropriate, any local variables.
  261.      If the FIND-FILE argument to `normal-mode' is non-`nil',
  262.      `normal-mode' assumes that the `find-file' function is calling it.
  263.      In this case, it may process a local variables list at the end of
  264.      the file.  The variable `enable-local-variables' controls whether
  265.      to do so.
  266.      If you run `normal-mode' yourself, the argument FIND-FILE is
  267.      normally `nil'.  In this case, `normal-mode' unconditionally
  268.      processes any local variables list.  *Note Local Variables in
  269.      Files: (emacs)File variables, for the syntax of the local
  270.      variables section of a file.
  271.      `normal-mode' uses `condition-case' around the call to the major
  272.      mode function, so errors are caught and reported as a `File mode
  273.      specification error',  followed by the original error message.
  274.  - User Option: enable-local-variables
  275.      This variable controls processing of local variables lists in files
  276.      being visited.  A value of `t' means process the local variables
  277.      lists unconditionally; `nil' means ignore them; anything else means
  278.      ask the user what to do for each file.  The default value is `t'.
  279.  - User Option: enable-local-eval
  280.      This variable controls processing of `Eval:' in local variables
  281.      lists in files being visited.  A value of `t' means process them
  282.      unconditionally; `nil' means ignore them; anything else means ask
  283.      the user what to do for each file.  The default value is `maybe'.
  284.  - Function: set-auto-mode
  285.      This function selects the major mode that is appropriate for the
  286.      current buffer.  It may base its decision on the value of the `-*-'
  287.      line, on the visited file name (using `auto-mode-alist'), or on the
  288.      value of a local variable).  However, this function does not look
  289.      for the `mode:' local variable near the end of a file; the
  290.      `hack-local-variables' function does that.  *Note How Major Modes
  291.      are Chosen: (emacs)Choosing Modes.
  292.  - User Option: default-major-mode
  293.      This variable holds the default major mode for new buffers.  The
  294.      standard value is `fundamental-mode'.
  295.      If the value of `default-major-mode' is `nil', Emacs uses the
  296.      (previously) current buffer's major mode for the major mode of a
  297.      new buffer.  However, if the major mode symbol has a `mode-class'
  298.      property with value `special', then it is not used for new buffers;
  299.      Fundamental mode is used instead.  The modes that have this
  300.      property are those such as Dired and Rmail that are useful only
  301.      with text that has been specially prepared.
  302.  - Variable: initial-major-mode
  303.      The value of this variable determines the major mode of the initial
  304.      `*scratch*' buffer.  The value should be a symbol that is a major
  305.      mode command name.  The default value is `lisp-interaction-mode'.
  306.  - Variable: auto-mode-alist
  307.      This variable contains an association list of file name patterns
  308.      (regular expressions; *note Regular Expressions::.) and
  309.      corresponding major mode functions.  Usually, the file name
  310.      patterns test for suffixes, such as `.el' and `.c', but this need
  311.      not be the case.  Each element of the alist looks like `(REGEXP .
  312.      mODE-FUNCTION)'.
  313.      For example,
  314.           (("^/tmp/fol/" . text-mode)
  315.            ("\\.texinfo$" . texinfo-mode)
  316.            ("\\.texi$" . texinfo-mode)
  317.           ("\\.el$" . emacs-lisp-mode)
  318.            ("\\.c$" . c-mode)
  319.            ("\\.h$" . c-mode)
  320.            ...)
  321.      When you visit a file whose *expanded* file name (*note File Name
  322.      Expansion::.) matches a REGEXP, `set-auto-mode' calls the
  323.      corresponding MODE-FUNCTION.  This feature enables Emacs to select
  324.      the proper major mode for most files.
  325.      Here is an example of how to prepend several pattern pairs to
  326.      `auto-mode-alist'.  (You might use this sort of expression in your
  327.      `.emacs' file.)
  328.           (setq auto-mode-alist
  329.             (append
  330.              ;; Filename starts with a dot.
  331.              '(("/\\.[^/]*$" . fundamental-mode)
  332.                ;; Filename has no dot.
  333.                ("[^\\./]*$" . fundamental-mode)
  334.                ("\\.C$" . c++-mode))
  335.              auto-mode-alist))
  336.  - Function: hack-local-variables &optional FORCE
  337.      This function parses, and binds or evaluates as appropriate, any
  338.      local variables for the current buffer.
  339.      The handling of `enable-local-variables' documented for
  340.      `normal-mode' actually takes place here.  The argument FORCE
  341.      reflects the argument FIND-FILE given to `normal-mode'.
  342. File: elisp,  Node: Mode Help,  Prev: Auto Major Mode,  Up: Major Modes
  343. Getting Help about a Major Mode
  344. -------------------------------
  345.    The `describe-mode' function is used to provide information about
  346. major modes.  It is normally called with `C-h m'.  The `describe-mode'
  347. function uses the value of `major-mode', which is why every major mode
  348. function needs to set the `major-mode' variable.
  349.  - Command: describe-mode
  350.      This function displays the documentation of the current major mode.
  351.      The `describe-mode' function calls the `documentation' function
  352.      using the value of `major-mode' as an argument.  Thus, it displays
  353.      the documentation string of the major mode function.  (*Note
  354.      Accessing Documentation::.)
  355.  - Variable: major-mode
  356.      This variable holds the symbol for the current buffer's major
  357.      mode.  This symbol should be the name of the function that is
  358.      called to initialize the mode.  The `describe-mode' function uses
  359.      the documentation string of this symbol as the documentation of
  360.      the major mode.
  361. File: elisp,  Node: Minor Modes,  Next: Mode Line Format,  Prev: Major Modes,  Up: Modes
  362. Minor Modes
  363. ===========
  364.    A "minor mode" provides features that users may enable or disable
  365. independently of the choice of major mode.  Minor modes can be enabled
  366. individually or in combination.  Minor modes would be better named
  367. "Generally available, optional feature modes" except that such a name is
  368. unwieldy.
  369.    A minor mode is not usually a modification of single major mode.  For
  370. example, Auto Fill mode may be used in any major mode that permits text
  371. insertion.  To be general, a minor mode must be effectively independent
  372. of the things major modes do.
  373.    A minor mode is often much more difficult to implement than a major
  374. mode.  One reason is that you should be able to deactivate a minor mode
  375. and restore the environment of the major mode to the state it was in
  376. before the minor mode was activated.
  377.    Often the biggest problem in implementing a minor mode is finding a
  378. way to insert the necessary hook into the rest of Emacs.  Minor mode
  379. keymaps make this easier.
  380. * Menu:
  381. * Minor Mode Conventions::      Tips for writing a minor mode.
  382. * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
  383. File: elisp,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes
  384. Conventions for Writing Minor Modes
  385. -----------------------------------
  386.    There are conventions for writing minor modes just as there are for
  387. major modes.  Several of the major mode conventions apply to minor
  388. modes as well: those regarding the name of the mode initialization
  389. function, the names of global symbols, and the use of keymaps and other
  390. tables.
  391.    In addition, there are several conventions that are specific to
  392. minor modes.
  393.    * Make a variable whose name ends in `-mode' to represent the minor
  394.      mode.  Its value should enable or disable the mode (`nil' to
  395.      disable; anything else to enable.)  We call this the "mode
  396.      variable".
  397.      This variable is used in conjunction with the `minor-mode-alist' to
  398.      display the minor mode name in the mode line.  It can also enable
  399.      or disable a minor mode keymap.  Individual commands or hooks can
  400.      also check the variable's value.
  401.      If you want the minor mode to be enabled separately in each buffer,
  402.      make the variable buffer-local.
  403.    * Define a command whose name is the same as the mode variable.  Its
  404.      job is to enable and disable the mode by setting the variable.
  405.      The command should accept one optional argument.  If the argument
  406.      is `nil', it should toggle the mode (turn it on if it is off, and
  407.      off if it is on).  Otherwise, it should turn the mode on if the
  408.      argument is a positive integer, a symbol other than `nil' or `-',
  409.      or a list whose CAR is such an integer or symbol; it should turn
  410.      the mode off otherwise.
  411.      Here is an example taken from the definition of `overwrite-mode'.
  412.      It shows the use of `overwrite-mode' as a variable which enables or
  413.      disables the mode's behavior.
  414.           (setq overwrite-mode
  415.                 (if (null arg) (not overwrite-mode)
  416.                   (> (prefix-numeric-value arg) 0)))
  417.    * Add an element to `minor-mode-alist' for each minor mode (*note
  418.      Mode Line Variables::.).  This element should be a list of the
  419.      following form:
  420.           (MODE-VARIABLE STRING)
  421.      Here MODE-VARIABLE is the variable that controls enablement of the
  422.      minor mode, and STRING is a short string, starting with a space,
  423.      to represent the mode in the mode line.  These strings must be
  424.      short so that there is room for several of them at once.
  425.      When you add an element to `minor-mode-alist', use `assq' to check
  426.      for an existing element, to avoid duplication.  For example:
  427.           (or (assq 'leif-mode minor-mode-alist)
  428.               (setq minor-mode-alist
  429.                     (cons '(leif-mode " Leif") minor-mode-alist)))
  430. File: elisp,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
  431. Keymaps and Minor Modes
  432. -----------------------
  433.    As of Emacs version 19, each minor mode can have its own keymap
  434. which is active when the mode is enabled.  *Note Active Keymaps::.  To
  435. set up a keymap for a minor mode, add an element to the alist
  436. `minor-mode-map-alist'.
  437.    One use of minor mode keymaps is to modify the behavior of certain
  438. self-inserting characters so that they do something else as well as
  439. self-insert.  This is the only way to accomplish this in general, since
  440. there is no way to customize what `self-insert-command' does except in
  441. certain special cases (designed for abbrevs and Auto Fill mode).  (Do
  442. not try substituting your own definition of `self-insert-command' for
  443. the standard one.  The editor command loop handles this function
  444. specially.)
  445.  - Variable: minor-mode-map-alist
  446.      This variable is an alist of elements element that look like this:
  447.           (VARIABLE . KEYMAP)
  448.      where VARIABLE is the variable which indicates whether the minor
  449.      mode is enabled, and KEYMAP is the keymap.  The keymap KEYMAP is
  450.      active whenever VARIABLE has a non-`nil' value.
  451.      Note that elements of `minor-mode-map-alist' do not have the same
  452.      structure as elements of `minor-mode-alist'.  The map must be the
  453.      CDR of the element; a list with the map as the second element will
  454.      not do.
  455.      What's more, the keymap itself must appear in the CDR.  It does not
  456.      work to store a variable in the CDR and make the map the value of
  457.      that variable.
  458.      When more than one minor mode keymap is active, their order of
  459.      priority is the order of `minor-mode-map-alist'.  But you should
  460.      design minor modes so that they don't interfere with each other.
  461.      If you do this properly, the order will not matter.
  462. File: elisp,  Node: Mode Line Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
  463. Mode Line Format
  464. ================
  465.    Each Emacs window (aside from minibuffer windows) includes a mode
  466. line which displays status information about the buffer displayed in the
  467. window.  The mode line contains information about the buffer such as its
  468. name, associated file, depth of recursive editing, and the major and
  469. minor modes of the buffer.
  470.    This section describes how the contents of the mode line are
  471. controlled.  It is in the chapter on modes because much of the
  472. information displayed in the mode line relates to the enabled major and
  473. minor modes.
  474.    `mode-line-format' is a buffer-local variable that holds a template
  475. used to display the mode line of the current buffer.  All windows for
  476. the same buffer use the same `mode-line-format' and the mode lines will
  477. appear the same (except perhaps for the percentage of the file scrolled
  478. off the top).
  479.    The mode line of a window is normally updated whenever a different
  480. buffer is shown in the window, or when the buffer's modified-status
  481. changes from `nil' to `t' or vice-versa.  If you modify any of the
  482. variables referenced by `mode-line-format', you may want to force an
  483. update of the mode line so as to display the new information.
  484.  - Function: force-mode-line-update
  485.      Force redisplay of the current buffer's mode line.
  486.    The mode line is usually displayed in inverse video; see
  487. `mode-line-inverse-video' in *Note Inverse Video::.
  488. * Menu:
  489. * Mode Line Data::        The data structure that controls the mode line.
  490. * Mode Line Variables::   Variables used in that data structure.
  491. * %-Constructs::          Putting information into a mode line.
  492. File: elisp,  Node: Mode Line Data,  Next: Mode Line Variables,  Prev: Mode Line Format,  Up: Mode Line Format
  493. The Data Structure of the Mode Line
  494. -----------------------------------
  495.    The mode line contents are controlled by a data structure of lists,
  496. strings, symbols and numbers kept in the buffer-local variable
  497. `mode-line-format'.  The data structure is called a "mode line
  498. construct", and it is built in recursive fashion out of simpler mode
  499. line constructs.
  500.  - Variable: mode-line-format
  501.      The value of this variable is a mode line construct with overall
  502.      responsibility for the mode line format.  The value of this
  503.      variable controls which other variables are used to form the mode
  504.      line text, and where they appear.
  505.    A mode line construct may be as simple as a fixed string of text, but
  506. it usually specifies how to use other variables to construct the text.
  507. Many of these variables are themselves defined to have mode line
  508. constructs as their values.
  509.    The default value of `mode-line-format' incorporates the values of
  510. variables such as `mode-name' and `minor-mode-alist'.  Because of this,
  511. very few modes need to alter `mode-line-format'.  For most purposes, it
  512. is sufficient to alter the variables referenced by `mode-line-format'.
  513.    A mode line construct may be a list, cons cell, symbol, or string.
  514. If the value is a list, each element may be a list, a cons cell, a
  515. symbol, or a string.
  516. `STRING'
  517.      A string as a mode line construct is displayed verbatim in the
  518.      mode line except for "`%'-constructs".  Decimal digits after the
  519.      `%' specify the field width for space filling on the right (i.e.,
  520.      the data is left justified).  *Note %-Constructs::.
  521. `SYMBOL'
  522.      A symbol as a mode line construct stands for its value.  The value
  523.      of SYMBOL is used in place of SYMBOL unless SYMBOL is `t' or
  524.      `nil', or is void, in which case SYMBOL is ignored.
  525.      There is one exception: if the value of SYMBOL is a string, it is
  526.      processed verbatim in that the `%'-constructs are not recognized.
  527. `(STRING REST...) or (LIST REST...)'
  528.      A list whose first element is a string or list, means to
  529.      concatenate all the elements.  This is the most common form of
  530.      mode line construct.
  531. `(SYMBOL THEN ELSE)'
  532.      A list whose first element is a symbol is a conditional.  Its
  533.      meaning depends on the value of SYMBOL.  If the value is non-`nil',
  534.      the second element of the list (THEN) is processed recursively as
  535.      a mode line element.  But if the value of SYMBOL is `nil', the
  536.      third element of the list (if there is one) is processed
  537.      recursively.
  538. `(WIDTH REST...)'
  539.      A list whose first element is an integer specifies truncation or
  540.      padding of the results of REST.  The remaining elements REST are
  541.      processed recursively as mode line constructs and concatenated
  542.      together.  Then the result is space filled (if WIDTH is positive)
  543.      or truncated (to -WIDTH columns, if WIDTH is negative) on the
  544.      right.
  545.      For example, the usual way to show what percentage of a buffer is
  546.      above the top of the window is to use a list like this: `(-3 .
  547.      "%p")'.
  548.    If you do alter `mode-line-format' itself, the new value should use
  549. all the same variables that are used by the default value, rather than
  550. duplicating their contents or displaying the information in another
  551. fashion.  This permits customizations made by the user, by libraries
  552. (such as `display-time') or by major modes via changes to those
  553. variables remain effective.
  554.    Here is an example of a `mode-line-format' that might be useful for
  555. `shell-mode' since it contains the hostname and default directory.
  556.      (setq mode-line-format
  557.        (list ""
  558.         'mode-line-modified
  559.         "%b--"
  560.         (getenv "HOST")      ; One element is not constant.
  561.         ":"
  562.         'default-directory
  563.         "   "
  564.         'global-mode-string
  565.         "   %[(" 'mode-name
  566.         'minor-mode-alist
  567.         "%n"
  568.         'mode-line-process
  569.         ")%]----"
  570.         '(-3 . "%p")
  571.         "-%-"))
  572. File: elisp,  Node: Mode Line Variables,  Next: %-Constructs,  Prev: Mode Line Data,  Up: Mode Line Format
  573. Variables Used in the Mode Line
  574. -------------------------------
  575.    This section describes variables incorporated by the standard value
  576. of `mode-line-format' into the text of the mode line.  There is nothing
  577. inherently special about these variables; any other variables could
  578. have the same effects on the mode line if `mode-line-format' were
  579. changed to use them.
  580.  - Variable: mode-line-modified
  581.      This variable holds the value of the mode-line construct that
  582.      displays whether the current buffer is modified.
  583.      The default value of `mode-line-modified' is `("--%1*%1*-")'.
  584.      This means that the mode line displays `--**-' if the buffer is
  585.      modified, `-----' if the buffer is not modified, and `--%%-' if
  586.      the buffer is read only.
  587.      Changing this variable does not force an update of the mode line.
  588.  - Variable: mode-line-buffer-identification
  589.      This variable identifies the buffer being displayed in the window.
  590.      Its default value is `Emacs: %17b', which means that it displays
  591.      `Emacs:' followed by the buffer name.  You may want to change this
  592.      in modes such as Rmail that do not behave like a "normal" Emacs.
  593.  - Variable: global-mode-string
  594.      This variable holds a string that is displayed in the mode line.
  595.      The command `display-time' puts the time and load in this variable.
  596.      The `%M' construct substitutes the value of `global-mode-string',
  597.      but this is obsolete, since the variable is included directly in
  598.      the mode line.
  599.  - Variable: mode-name
  600.      This buffer-local variable holds the "pretty" name of the current
  601.      buffer's major mode.  Each major mode should set this variable so
  602.      that the mode name will appear in the mode line.
  603.  - Variable: minor-mode-alist
  604.      This variable holds an association list whose elements specify how
  605.      the mode line should indicate that a minor mode is active.  Each
  606.      element of the `minor-mode-alist' should be a two-element list:
  607.           (MINOR-MODE-VARIABLE MODE-LINE-STRING)
  608.      The string MODE-LINE-STRING is included in the mode line when the
  609.      value of MINOR-MODE-VARIABLE is non-`nil' and not otherwise.
  610.      These strings should begin with spaces so that they don't run
  611.      together.  Conventionally, the MINOR-MODE-VARIABLE for a specific
  612.      mode is set to a non-`nil' value when that minor mode is activated.
  613.      The default value of `minor-mode-alist' is:
  614.           minor-mode-alist
  615.           => ((abbrev-mode " Abbrev")
  616.               (overwrite-mode " Ovwrt")
  617.               (auto-fill-function " Fill")
  618.               (defining-kbd-macro " Def"))
  619.      (In earlier Emacs versions, `auto-fill-function' was called
  620.      `auto-fill-hook'.)
  621.      `minor-mode-alist' is not buffer-local.  The variables mentioned
  622.      in the alist should be buffer-local if the minor mode can be
  623.      enabled separately in each buffer.
  624.  - Variable: mode-line-process
  625.      This buffer-local variable contains the mode line information on
  626.      process status in modes used for communicating with subprocesses.
  627.      It is displayed immediately following the major mode name, with no
  628.      intervening space.  For example, its value in the `*shell*' buffer
  629.      is `(": %s")', which allows the shell to display its status along
  630.      with the major mode as: `(Shell: run)'.  Normally this variable is
  631.      `nil'.
  632.  - Variable: default-mode-line-format
  633.      This variable holds the default `mode-line-format' for buffers
  634.      that do not override it.  This is the same as `(default-value
  635.      'mode-line-format)'.
  636.      The default value of `default-mode-line-format' is:
  637.           (""
  638.            mode-line-modified
  639.            mode-line-buffer-identification
  640.            "   "
  641.            global-mode-string
  642.            "   %[("
  643.            mode-name
  644.            minor-mode-alist
  645.            "%n"
  646.            mode-line-process
  647.            ")%]----"
  648.            (-3 . "%p")
  649.            "-%-")
  650. File: elisp,  Node: %-Constructs,  Prev: Mode Line Variables,  Up: Mode Line Format
  651. `%'-Constructs in the Mode Line
  652. -------------------------------
  653.    The following table lists the recognized `%'-constructs and what
  654. they mean.
  655.      the current buffer name, using the `buffer-name' function.
  656.      the visited file name, using the `buffer-file-name' function.
  657.      `%' if the buffer is read only (see `buffer-read-only');
  658.      `*' if the buffer is modified (see `buffer-modified-p');
  659.      `-' otherwise.
  660.      the status of the subprocess belonging to the current buffer, using
  661.      `process-status'.
  662.      the percent of the buffer above the top of window, or `Top',
  663.      `Bottom' or `All'.
  664.      `Narrow' when narrowing is in effect; nothing otherwise (see
  665.      `narrow-to-region' in *Note Narrowing::).
  666.      an indication of the depth of recursive editing levels (not
  667.      counting minibuffer levels): one `[' for each editing level.
  668.      one `]' for each recursive editing level (not counting minibuffer
  669.      levels).
  670.      the character `%'--this is how to include a literal `%' in a
  671.      string in which `%'-constructs are allowed.
  672.      dashes sufficient to fill the remainder of the mode line.
  673.    The following two `%'-constructs are still supported but are
  674. obsolete since use of the `mode-name' and `global-mode-string'
  675. variables will produce the same results.
  676.      the value of `mode-name'.
  677.      the value of `global-mode-string'.  Currently, only `display-time'
  678.      modifies the value of `global-mode-string'.
  679. File: elisp,  Node: Hooks,  Prev: Mode Line Format,  Up: Modes
  680. Hooks
  681. =====
  682.    A "hook" is a variable where you can store a function or functions
  683. to be called on a particular occasion by an existing program.  Emacs
  684. provides lots of hooks for the sake of customization.  Most often, hooks
  685. are set up in the `.emacs' file, but Lisp programs can set them also.
  686. *Note Standard Hooks::, for a list of standard hook variables.
  687.    Most of the hooks in Emacs are "normal hooks".  These variables
  688. contain lists of functions to be called with no arguments.  The reason
  689. most hooks are normal hooks is so that you can use them in a uniform
  690. way.  You can always tell when a hook is a normal hook, because its
  691. name ends in `-hook'.
  692.    The recommended way to add a hook function to a normal hook is by
  693. calling `add-hook' (see below).  The hook functions may be any of the
  694. valid kinds of functions that `funcall' accepts (*note What Is a
  695. Function::.).  Most normal hook variables are initially void;
  696. `add-hook' knows how to deal with this.
  697.    As for abnormal hooks, those whose names end in `-function' have a
  698. value which is a single function.  Those whose names end in `-hooks'
  699. have a value which is a list of functions.  Any hook which is abnormal
  700. is abnormal because a normal hook won't do the job; either the
  701. functions are called with arguments, or their values are meaningful.
  702. The name shows you that the hook is abnormal and you need to look up
  703. how to use it properly.
  704.    Most major modes run hooks as the last step of initialization.  This
  705. makes it easy for a user to customize the behavior of the mode, by
  706. overriding the local variable assignments already made by the mode.  But
  707. hooks may also be used in other contexts.  For example, the hook
  708. `suspend-hook' runs just before Emacs suspends itself (*note Suspending
  709. Emacs::.).
  710.    For example, you can put the following expression in your `.emacs'
  711. file if you want to turn on Auto Fill mode when in Lisp Interaction
  712. mode:
  713.      (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
  714.    The next example shows how to use a hook to customize the way Emacs
  715. formats C code.  (People often have strong personal preferences for one
  716. format compared to another.)  Here the hook function is an anonymous
  717. lambda expression.
  718.      (add-hook 'c-mode-hook
  719.        (function (lambda ()
  720.                    (setq c-indent-level 4
  721.                          c-argdecl-indent 0
  722.                          c-label-offset -4
  723.                          c-continued-statement-indent 0
  724.                          c-brace-offset 0
  725.                          comment-column 40))))
  726.      
  727.      (setq c++-mode-hook c-mode-hook)
  728.    Finally, here is an example of how to use the Text mode hook to
  729. provide a customized mode line for buffers in Text mode, displaying the
  730. default directory in addition to the standard components of the mode
  731. line.  (This may cause the mode line to run out of space if you have
  732. very long file names or display the time and load.)
  733.      (add-hook 'text-mode-hook
  734.        (function (lambda ()
  735.                    (setq mode-line-format
  736.                          '(mode-line-modified
  737.                            "Emacs: %14b"
  738.                            "  "
  739.                            default-directory
  740.                            " "
  741.                            global-mode-string
  742.                            "%[("
  743.                            mode-name
  744.                            minor-mode-alist
  745.                            "%n"
  746.                            mode-line-process
  747.                            ") %]---"
  748.                            (-3 . "%p")
  749.                            "-%-")))))
  750.    At the appropriate time, Emacs uses the `run-hooks' function to run
  751. particular hooks.  This function calls the hook functions you have
  752. added with `add-hooks'.
  753.  - Function: run-hooks &rest HOOKVAR
  754.      This function takes one or more hook names as arguments and runs
  755.      each one in turn.  Each HOOKVAR argument should be a symbol that
  756.      is a hook variable.  These arguments are processed in the order
  757.      specified.
  758.      If a hook variable has a non-`nil' value, that value may be a
  759.      function or a list of functions.  If the value is a function
  760.      (either a lambda expression or a symbol with a function
  761.      definition), it is called.  If it is a list, the elements are
  762.      called, in order.  The hook functions are called with no arguments.
  763.      For example:
  764.           (run-hooks 'emacs-lisp-mode-hook)
  765.      Major mode functions use this function to call any hooks defined
  766.      by the user.
  767.  - Function: add-hook HOOK FUNCTION &optional APPEND
  768.      This function is the handy way to add function FUNCTION to hook
  769.      variable HOOK.  For example,
  770.           (add-hook 'text-mode-hook 'my-text-hook-function)
  771.      adds `my-text-hook-function' to the hook called `text-mode-hook'.
  772.      It is best to design your hook functions so that the order in
  773.      which they are executed does not matter.  Any dependence on the
  774.      order is "asking for trouble."  However, the order is predictable:
  775.      normally, FUNCTION goes at the front of the hook list, so it will
  776.      be executed first (barring another `add-hook' call).
  777.      If the optional argument APPEND is non-`nil', the new hook
  778.      function goes at the end of the hook list and will be executed
  779.      last.
  780. File: elisp,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top
  781. Documentation
  782. *************
  783.    GNU Emacs Lisp has convenient on-line help facilities, most of which
  784. derive their information from the documentation strings associated with
  785. functions and variables.  This chapter describes how to write good
  786. documentation strings for your Lisp programs, as well as how to write
  787. programs to access documentation.
  788.    Note that the documentation strings for Emacs are not the same thing
  789. as the Emacs manual.  Manuals have their own source files, written in
  790. the Texinfo language; documentation strings are specified in the
  791. definitions of the functions and variables they apply to.  A collection
  792. of documentation strings is not sufficient as a manual because a good
  793. manual is not organized in that fashion; it is organized in terms of
  794. topics of discussion.
  795. * Menu:
  796. * Documentation Basics::      Good style for doc strings.
  797.                                 Where to put them.  How Emacs stores them.
  798. * Accessing Documentation::   How Lisp programs can access doc strings.
  799. * Keys in Documentation::     Substituting current key bindings.
  800. * Describing Characters::     Making printable descriptions of
  801.                                 non-printing characters and key sequences.
  802. * Help Functions::            Subroutines used by Emacs help facilities.
  803. File: elisp,  Node: Documentation Basics,  Next: Accessing Documentation,  Prev: Documentation,  Up: Documentation
  804. Documentation Basics
  805. ====================
  806.    A documentation string is written using the Lisp syntax for strings,
  807. with double-quote characters surrounding the text of the string.  This
  808. is because it really is a Lisp string object.  The string serves as
  809. documentation when it is written in the proper place in the definition
  810. of a function or variable.  In a function definition, the documentation
  811. string follows the argument list.  In a variable definition, the
  812. documentation string follows the initial value of the variable.
  813.    When you write a documentation string, make the first line a complete
  814. sentence (or two complete sentences) since some commands, such as
  815. `apropos', print only the first line of a multi-line documentation
  816. string.  Also, you should not indent the second line of a documentation
  817. string, if you have one, because that looks odd when you use `C-h f'
  818. (`describe-function') or `C-h v' (`describe-variable').
  819.    Documentation strings may contain several special substrings, which
  820. stand for key bindings to be looked up in the current keymaps when the
  821. documentation is displayed.  This allows documentation strings to refer
  822. to the keys for related commands and be accurate even when a user
  823. rearranges the key bindings.  (*Note Accessing Documentation::.)
  824.    Within the Lisp world, a documentation string is kept with the
  825. function or variable that it describes:
  826.    * The documentation for a function is stored in the function
  827.      definition itself (*note Lambda Expressions::.).  The function
  828.      `documentation' knows how to extract it.
  829.    * The documentation for a variable is stored on the variable's
  830.      property list under the property name `variable-documentation'.
  831.      The function `documentation-property' knows how to extract it.
  832.    However, to save space, the documentation for preloaded functions and
  833. variables (including primitive functions and autoloaded functions) are
  834. stored in the `emacs/etc/DOC-VERSION' file.  Both the `documentation'
  835. and the `documentation-property' functions know how to access
  836. `emacs/etc/DOC-VERSION', and the process is transparent to the user.
  837. In this case, the documentation string is replaced with an integer
  838. offset into the `emacs/etc/DOC-VERSION' file.  Keeping the documentation
  839. strings out of the Emacs core image saves a significant amount of space.
  840. *Note Building Emacs::.
  841.    For information on the uses of documentation strings, see *Note
  842. Help: (emacs)Help.
  843.    The `emacs/etc' directory contains two utilities that you can use to
  844. print nice-looking hardcopy for the file `emacs/etc/DOC-VERSION'.
  845. These are `sorted-doc.c' and `digest-doc.c'.
  846.